.Net Core Web Api_筆記21_Swagger及OpenAPI介紹與配置使用方式_API管理與測試探討

2021 iThome 鐵人賽

自我挑戰組

.NET Core WebApi網頁應用開發系列第 21 篇

13th鐵人賽

Samuel

2021-12-23 15:09:00

8454 瀏覽

分享至

Swagger 是一套web api管理於測試的工具
甚至可協助提供自訂API規格文件與呼叫回應方式的描述

以下是台中交通API的實際案例
https://datacenter.taichung.gov.tw/swagger/api-docs/

於2015年Swagger就捐贈給OpenAPI計畫
也因此有OpenAPI的別稱

不過通常習慣將OpenAPI視為一種規範而Swagger則是實踐該規範的工具。
OpenAPI 注重開發者寫出來的API可跟調用呼叫者很直接的合作而不用透過程式碼存取

我們可從OpenAPI規範看出訪問的URL與HTTP Method採用何種(GET,PUT,POST...)
跟參數與資料型別

因此用戶端可以很清楚如何去呼叫使用更能讓二次開發者能夠無縫接軌

Swagger其實相當於一個根據OpenAPI規範發展出來一系列產品的品牌。
旗下也有諸多不同的工具比方OpenAPIGenerator , NSwag , Swashbuckle ....

Swagger UI 則是提供了Web 介面使用OpenAPI規範提供資訊。

而我們於.NET Core開發框架則可透過middleware方式註冊NSwag , Swashbuckle

Swagger 3 Web UI

Swagger 2 Web UI

.net core web api應用Swagger配置使用

在此我拿之前跑的這幾篇最終產出的專案去配置

.Net Core Web Api_筆記13_api結合ADO.NET資料庫操作part1_專案前置準備到資料新增

.Net Core Web Api_筆記14_api結合ADO.NET資料庫操作part2_資料查詢呈現

.Net Core Web Api_筆記15_api結合ADO.NET資料庫操作part3_資料刪除

.Net Core Web Api_筆記16_api結合ADO.NET資料庫操作part4_資料編輯提交更新

.Net Core Web Api_筆記17_api結合ADO.NET資料庫操作part5_新聞文章新增_新聞類別元素透過API綁定方式

.Net Core Web Api_筆記18_api結合ADO.NET資料庫操作part6_新聞文章表格陳列查詢

.Net Core Web Api_筆記19_api結合ADO.NET資料庫操作part7_新聞文章的編輯更新與刪除

.Net Core Web Api_筆記20_api結合ADO.NET資料庫操作part8_新聞文章查詢

到Nuget套件去下載安裝NSwag.AspNetCore

緊接著我們到Starup的ConfigureServices方法去註冊服務

再到Configure去啟用OpenAPI跟SwaggerUI的中間件

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;

namespace MyNet5ApiAdoTest
{
    public class Startup
    {
        public Startup(IConfiguration configuration)
        {
            Configuration = configuration;
        }

        public IConfiguration Configuration { get; }

        // This method gets called by the runtime. Use this method to add services to the container.
        public void ConfigureServices(IServiceCollection services)
        {
            services.AddControllers();
            services.AddSwaggerDocument();//註冊NSwag提供的服務
        }

        // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
        public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }            

            app.UseStaticFiles();
            app.UseRouting();

            app.UseAuthorization();

            app.UseOpenApi();//啟用OpenAPI,預設路由/swagger/v1/swagger.json

            app.UseSwaggerUi3();//啟用SwaggerUi version 3

            app.UseEndpoints(endpoints =>
            {
                endpoints.MapControllers();
            });
        }
    }
}

最後就是見證奇蹟的時刻(對於懶得寫API文件的開發者來說真的是一大福音)
要查看Swagger API 自動幫我們掃描所有API 方法後產生出來的WEB API Document
預設路由/swagger
會自動跳轉至/swagger/index.html